©Copyright 1995 Rogue Wave Software
Figure 1 shows an overview of the Net.h++ layered architecture. Figures 2-5 show the classes and their relationships to one another within the various Net.h++ layers. The following conventions are used in the figures.
RWInetHostNotFound: no internet port with given service name
This is an external error because services which may be defined on one machine may not necessarily be defined on another. The only way to make sure is to use a port number instead of a string.
RWInetServiceNotFound: no internet port with given service name
This is an external error because services which may be defined on one machine may not necessarily be defined on another. The only way to make sure is to use a port number instead of a string.
RWNetAlreadyRegistered: another address factory already registered
You have attempted to register two different address factories with a general address factory for the same family key.
RWNetCantCreatePortal: cannot create a communications endpoint
RWNetCant[Send,Recv]: can't send/receive data from channel
No data can be sent/received from the communications channel. One possibility is that the channel is non-blocking and you attempted to do a guaranteedSend()/guaranteedRecv() on a portal.
RWNetInvalidSocket: tried to use an invalid socket
This is thrown when you try to use a socket that is not valid. RWSockets are invalid until they are initialized.
RWNetNoChannel: there is no underlying communications channel
This exception is thrown when you attempt to access communications via a portal with no underlying communications channel present. This happens when you build a Portal with the default constructor and then don't assign anything to it.
RWNetNoFactoryRegistered: no factory has been registered for this family
You are attempting to build a socket address for a family for which no socket address factory has been registered. The derived classes RWNetNoNumberFactoryRegistered and RWNetNoNameFactoryRegistered handle the cases of families identified via number or name, respectively.
RWNetNoSuchBlockingHook: specified an invalid blocking hook ID
You specified an ID of a Net.h++ blocking hook that does no exist.
RWNetNoWinsock: problem initializing the Winsock DLL
The Winsock DLL couldn't be initialized by the application. This could be due to the DLL not supporting the correct version of Winsock, for example. This exception is also thrown if there are problems shutting down the Winsock DLL after we are finished with it. This should be a rare condition.
RWNetSelectException: select returned an exceptional condition
For some reason, select returned a negative one. Keep track of the actual error number.
RWSockBadAddressFormat: tried to input an address I cannot understand
The input string cannot be parsed as an address. This is thrown from one of the constructors which convert a string to an address, or to an address component (like a host name).
RWSockErr: error thrown by the socket wrapper
This exception is thrown by the socket wrapper layer in response to a socket problem. The error code it carries indicates which error it was.
RWSockTypeChange: tried to bind/connect with address of wrong family
You tried to change the type of an RWSocket using bind() or connect(), by first setting up the state of a socket (using socket(), probably) and then by calling a function which takes an address.
RWSockWrongAddressType: tried to convert to wrong address type
You attempted to do a narrowing conversion to a class which is not a type of the object.
Return to Top of File.RWInetAddrRWInetPort
RWInetAddr contains RWInetPort
#include <rw/net/inetaddr.h>
RWInetPort port("discard");
Encapsulates an internet port and its service names. You can construct an RWInetPort from either an explicit port number or a symbolic service name.
Return to Top of File.RWInetTypeRWSockType
RWInetType inherits from RWSockType
#include <rw/net/inetaddr.h> RWSockType inet = RWInetType();
The internet address type. This class provides a convenient mechanism to construct an RWSockType for an internet address type. Since this class adds no state, instances can be converted to RWSockType with no loss of information.
Return to Top of File.RWInetAddrFactoryRWSockAddrBase
RWInetAddrFactory inherits from RWSockAddrFactoryBase which creates RWSockAddrBase
#include <rw/net/inetfact.h>
RWInetAddrFactory is used by the rwSockAddrFactory to create instances of RWInetAddr. It is not used directly by clients of Net.h++. Only a single instance of RWInetAddrFactory exists; it is created at the time the RWSockAddrFactory is constructed.
Return to Top of File.RWInetAddr
RWInetAddr contains RWInetHost
#include <rw/net/inetaddr.h>
RWInetHost host("objects.roguewave.com")
Encapsulates an internet host IP address and its names. You can construct an RWInetHost from either an IP address or a symbolic name.
Return to Top of File.RWInetAddr
RWInetAddr inherits from RWSockAddrBase
#include <rw/net/inetaddr.h> RWInetAddr addr(80, "www.roguewave.com");
A complete internet address that includes type information, a host, and a port.
Return to Top of File.RWPortalStreamBase
RWPortalStreamBase contains RWPortalStreambuf which contains RWPortal
#include <rw/net/portstrm.h>
This class provides functionality common to RWPortalIStream and RWPortalOStream.
Return to Top of File.RWPortalStreambuf
RWPortalStreambuf contains RWPortal
#include <rw/net/portstrm.h>
An RWPortalStreambuf is a streambuf that uses an RWPortal as its source and sink of bytes. It is used by RWPortalIStream and RWPortalOStream.
Return to Top of File.#include <rw/net/portal.h>
RWPortal portal = RWSocketPortal(RWInetAddr(42,
"tsunami.roguewave.com"));
A portal is an access point of a reliable byte stream communication channel. It is possible for more than one portal to access the communications channel. This happens, for example, when using the copy constructor and assignment operator. Unless explicitly constructed otherwise, portal classes are designed so that when the last portal into a channel disappears, the communications channel is closed.
Portals are lightweight objects. Since copying and assignment copy only the portal, and not the underlying communications channel, these operations are inexpensive. As a result, portals can be returned from functions and used as member data in objects.
Portals are implemented using the interface-implementation design pattern as described in the Net.h++ User's Guide. The portal itself is really a handle to an implementation that represents the communication channel.
Return to Top of File.
RWPortalOStream inherits from ostream and from RWPortalStreamBase
#include <rw/net/portstrm.h> RWPortalOStream strm(RWSocketPortal(sock));
This class provides an ostream that uses an RWPortal as its sink of bytes. The RWPortal can be attached to any of the communications channels supported by Net.h++.
Return to Top of File.
RWPortalIStream inherits from istream and from RWPortalStreamBase
#include <rw/net/portstrm.h> RWPortalIStream strm(RWSocketPortal(80, "www.roguewave.com"));
This class provides an istream that uses an RWPortal as its source of bytes. The RWPortal can be attached to any of the communications channels supported by Net.h++.
Return to Top of File.#include <rw/net/sockprot.h> RWSocketListener listener(RWInetAddr(71));
A socket listener waits on a specified socket address for incoming connections. Connections are obtained as RWSocketPortals.
Return to Top of File.#include <rw/net/socket.h> RWSocket socket;
RWSocket is a wrapper for the C concept of a socket. Its member functions correspond exactly with the C functions in the Berkeley sockets API. Typically, RWSocket member functions have the same names as the corresponding C API functions, but the arguments and return values may be different to reflect the C++ environment. For example, many member functions have default arguments to handle the most common cases. Some member functions take alternate parameter types which simplify the interface (e.g., using the RWSockAddrBase class instead of the sockaddr structure.). Sometimes, multiple overloadings of a member function exist to provide alternate APIs for different occasions.
Almost all of the Berkeley sockets calls that deal with a single socket are encapsulated in this class. There are a few calls left out:
In addition to the functions which match the sockets API, some convenience functions are also provided. These are the functions id(), valid(), socket(), recvAtLeast(), and sendAtLeast().
The socket is not shut down by a destructor. It must be explicitly shut down by calling close(), closesocket(), or shutdown(). Use the RWPortal layer for objects that close the portal automatically using a destructor.
The socket portal provided by RWSocket has no state. All state (whether the socket blocks, etc.) is kept in the communications channel.
Return to Top of File.RWSockAddrFactoryBase
RWSockAddrFactoryBase creates RWSockAddrBase
#include <rw/net/sockaddr.h>
RWSockAddrFactoryBase is an abstract class that builds socket addresses. It represents the concept of something that can build socket addresses from either the C API representation or an input stream.
Return to Top of File.RWSockAddrBaseRWSockType
RWSockAddrBase references RWSockType
#include <rw/net/sockaddr.h>
The RWSockAddrBase class is an interface class that represents a socket address. All member functions are pure virtual. A specific derived class is RWInetSockAddr defined in its own header file. The class RWSockAddr is a proxy class that provides an interface to an RW SockAddrBase object whose exact type is known.
Return to Top of File.#include <rw/net/sockaddr.h>
RWSockType represents a type of socket communications channel. It has three components: the family, the type, and the protocol. You cannot construct a valid RWSockType directly. Instead, derived classes, such as RWInetSockType, can be constructed and assigned to an RWSockType.
An RWSockType represents a type of socket communications, but without an address attached to it. It is made up of a family (sometimes called a domain), a socket type, and a protocol. An example of a family is the Internet TCP/IP family. A socket type is stream or datagram. A protocol could be TCP or UDP.
Return to Top of File.#include <rw/net/sockatt.h> RWSocketAttribute(socket, RWSocketAttribute::CANREAD)
The RWSocketAttribute class encapsulates conditions that may be true for a socket. An RW SocketAttribute serves two purposes: it is used to represent a set of attributes on a socket in which you may be interested, and it is used to indicate that a particular attribute is true. It consists of two parts: the socket, and the attribute.
The RWSocketAttribute class is used by the global function select() to do asynchronous I/O.
Return to Top of File.RWSockAddrFactory
RWSockAddrFactory inherits from RWSockAddrFactoryBase which creates RWSockAddrBase
#include <rw/net/sockaddr.h>
RWSockAddrFactory builds addresses of any (registered) type. This class is used by the Net.h++ implementation and is not normally used explicitly. The global object rwSockAddrFactory is used by functions like RWSocket::getsockname, which do not know the type of socket address they need to build.
There are two stages to building an address using this factory. First, the type of address is determined. Next, the type of address is used to look up an RWSockAddrFactoryBase object, which is used to actually construct the address. Note that since an RWSockAddrFactory is itself an RWSockAddrFactoryBase, this scheme can be used in a hierarchical fashion.
The types are indicated to the factory by either the address family integer identifier (as defined by the C sockets API) or a string. From there, the factory invokes a factory that is specific to the address family. It finds the specific factory using a dictionary kept with the factory.
Specific address factory objects need to be registered with the factory via the general factory's register() method. Check RWInetAddrFactory for an example of a specific address family factory. In an initial prototype code line we experimented with using a template class for specific address families, but found that subtle differences between the families and subtle template bugs in some compilers made this approach more trouble that it was worth.
All singleton objects are constructed explicitly rather than relying on static initialization. This way we have no dependence on order of static initialization.
Return to Top of File.RWSocketPortal
RWSocketPortal inherits from RWPortal RWSocketPortal references RWSocket
#include <rw/net/sockport.h>
RWPortal portal = RWSocketPortal(RWInetAddr(42,
"life.roguewave.com"));
This class provides a socket implementation of a portal, implemented using the RWSocket class. There is no state added to RWPortal. This implies you can assign an RWSocketPortal to an RWPortal with no loss of data (except for the type).
The socket representing RWSocketPortal's communication channel is normally closed when the last portal into the channel is destroyed. It is possible to prevent this by using a special constructor.
Return to Top of File.RWSockAddr
RWSockAddr inherits from RWSockAddrBase
#include <rw/net/sockaddr.h>
An RWSockAddr is a proxy to a socket address of a type which in not known until runtime. The RW SockAddr keeps a handle to a reference counted RWSockAddrBase object, which is the real address; the RWSockAddr passes requests on to this object.
Return to Top of File.